home *** CD-ROM | disk | FTP | other *** search
/ Programmer Power Tools / Programmer Power Tools.iso / progjrn / pj_7_6.arc / WINDEV.ARC / WPMAUX.DOC < prev   
Text File  |  1989-03-16  |  9KB  |  240 lines
  1.  
  2.  
  3.  
  4.               WINAUX/PMAUX
  5.  
  6.              William S. Hall
  7.              3665 Benton Street, #66
  8.               Santa Clara, CA 95051
  9.  
  10.               Introduction
  11.  
  12.  
  13.      Winaux is a Windows program capable of displaying text sent
  14. to it by another window.  PMaux is the corresponding version for
  15. presentation manager.  Acting as a simple scrolling window, each
  16. performs many of the operations of an auxiliary terminal.  They
  17. are particularly useful for analyzing the behavior of Windows or
  18. PM functions and for print-statement debugging.
  19.  
  20.      We begin by describing Winaux.  Please read this section even
  21. if you are planning to use PMaux.
  22.  
  23.  
  24.               Using Winaux
  25.  
  26.      Winaux is very easy to use.  When Winaux runs, it leaves a
  27. copy of its Window handle in win.ini.  Another program can then
  28. write to Winaux by sending it a message using the call
  29.  
  30.     SendMessage(hWnd, WM_USER, (WORD)len, (LONG)(LPSTR)str);
  31.  
  32. where hWnd is the window handle (which can be retrieved from
  33. win.ini), str is a string of characters, and len is its length. 
  34. In practice, the operation is made simpler by writing a function
  35. which will carry out the operations of retrieving the handle,
  36. calculating the length, and sending the message.  This function
  37. can be placed into an include file and used as needed by the
  38. target program.
  39.  
  40.      Winaux also creates a file called Winaux.log.  Using the
  41. Options menu, you can choose to log part or all of the session to
  42. disk.  The file is automatically closed when Winaux is exited.
  43. You should rename it if you want to preserve its contents before
  44. the next use of Winaux.
  45.  
  46.      When Winaux exits, it resets the value of the handle in
  47. win.ini to 0.  Hence programs which test for a valid window
  48. handle before attempting the SendMessage call will usually not
  49. risk the danger of accessing an invalid window.  However, if
  50. Windows is terminated abruptly by a crash, the handle in win.ini
  51. will not be NULL.  A program which calls Winaux using this handle
  52. may crash the system if it runs before and makes a call to
  53. Winaux.  Under these circumstances, you should edit win.ini and
  54. change the handle entry to 0. 
  55.  
  56.      Only one instance of Winaux is allowed.
  57.  
  58.      The very first time Winaux runs, it will choose a default
  59. position and size on the screen and write these parameters to
  60. win.ini.  The user can modify these values to place Winaux as
  61. desired.  A typical entry in win.ini is as follows:
  62.  
  63.     [Winaux]
  64.     x=100
  65.     y=275
  66.     cx=540
  67.     cy=75
  68.     hWnd=4589
  69.  
  70. This window will be positioned at pixel location (100,275) on the
  71. display and will be 540 pixels wide and 75 high.  On an EGA, this
  72. will place the window in the lower right corner.
  73.  
  74.      If you are using Winaux to help you debug a Windows program,
  75. then you will find it useful to experiment with the position and
  76. size and then add Winaux to your load or run line in win.ini.  As
  77. you go repeatedly through the compile-program, run-Windows,
  78. test-program, exit-Windows cycle, you will appreciate WINAUX more
  79. if you do not have to bother with running and positioning its
  80. window repeatedly.
  81.  
  82.      Winaux creates a text buffer with as many lines as your
  83. maximized display can show when using the system font. 
  84. Similarly, the number of characters per line is computed based on
  85. the maximum width of the display and the size of the system font.
  86.  
  87.      Lines are displayed at the bottom of the window and scroll
  88. upward.  The bigger the window the more lines will be visible. 
  89. Currently, there are no scroll bars, so once a line number
  90. exceeds the maximum number of lines, it is lost.
  91.  
  92.      Winaux converts newlines to a carriage-return line-feed
  93. pair.  A menu option allows you to kill this option.  However,
  94. lines are wrapped if they exceed the maximum number of horizontal
  95. characters on a line.
  96.  
  97.      At any time, you can clear the sreen with the corresponding
  98. menu item.
  99.  
  100.      To illustrate the program's application, we have included a
  101. simple Windows template called Smltpl in which a sprintf
  102. statement has been added at the top of the message loop.  All
  103. message parameters, and a counter, are printed to a buffer which
  104. is sent by the function auxprt to the Winaux window.  Auxprt
  105. itself is defined in the include files auxprt.c and auxprt.h.
  106.  
  107.     long FAR PASCAL MainWndProc( hWnd, message, wParam, lParam )
  108.     HWND hWnd;
  109.     unsigned message;
  110.     WORD wParam;
  111.     LONG lParam;
  112.     {
  113.         PAINTSTRUCT ps;
  114.  
  115.         /* print messages to Winaux */
  116.         sprintf(auxbuf,"hWnd = %4x message = %4x wParam = %4x lParam = %8lx\n",
  117.                  hWnd, message, wParam, lParam);
  118.         auxprt(auxbuf);
  119.  
  120.             ........
  121.  
  122.  
  123. Near the top of the program is an include statement
  124.  
  125.     #include "auxprt.c"
  126.  
  127. Auxprt.c contains the coded needed to communicate with WINAUX and
  128. is placed in the program's main module before WinMain.  Auxprt.c
  129. itself has an include statement for auxprt.h, a file containing
  130. a data declaration and a function prototype.  This file should
  131. be placed in any other module in which auxprt is to be called.
  132.  
  133. Auxprt.c and auxprt.h together have the following general form:
  134.  
  135.     char auxbuf[80];
  136.     auxprt(char *str)
  137.     {
  138.         HWND hWnd;
  139.         int len = strlen(str);
  140.  
  141.     #if defined(WINAUX)
  142.         hWnd = (HWND)GetProfileInt((LPSTR)"Winaux", (LPSTR)"hWnd", 0);
  143.         if (IsWindow(hWnd))
  144.             SendMessage(hWnd, WM_USER, (WORD)len, (LONG)(LPSTR)str);
  145.     #endif
  146.     
  147.     .... /* code for PM */
  148.     }
  149.  
  150.      Whenever a message is received, sprintf formats it and hands
  151. it to auxbuf.  The function auxbuf reads the Winaux handle,
  152. computes the length of the string, verifies that the handle
  153. received is valid, and sends it to Winaux.
  154.  
  155.      You can watch the messages being displayed by running
  156. Winaux, then Smltpl.  The action is especially swift as the mouse
  157. is moved over the Smltpl window.  You can also run more than one
  158. instance of the program and see the messages for each.
  159.  
  160.      Although reading the handle from win.ini may seem wasteful,
  161. it is an (almost) solid guarantee that the handle retrieved is
  162. either valid (Winaux is running) or NULL (Winaux has exited). 
  163. Also note the use of SendMessage rather than PostMessage.  Since
  164. Winaux will be retrieving a long pointer to data, SendMessage
  165. insures that the pointer is valid during the time that the data
  166. is being displayed. 
  167.  
  168.  
  169.                Using PMaux
  170.  
  171.      When PMaux runs, it leaves a copy of its window handle in
  172. os2.ini.  However, it is more difficult in PM to get the buffer
  173. from the other program over to PMaux since the data segment of
  174. one program is not accessible to another in protected mode.  In
  175. this case it is necessary to create a global, shareable buffer in
  176. the program calling PMaux, fill it, and pass the handle and the
  177. buffer length over to PMaux.  The following excerpt from the
  178. include files auxprt.c/auxprt.h describes the method. 
  179.  
  180.     char auxbuf[80];
  181.     auxprt(char *str)
  182.     {
  183.         HWND hWnd;
  184.         int len = strlen(str);
  185.  
  186.     ... /* code for Windows */
  187.  
  188.     #if defined(PMAUX)
  189.         char hbuf[40];
  190.         SEL sel;
  191.         PCH pchBuf;
  192.         int i;
  193.  
  194.   /* get the string representation of the handle for pmaux from OS2.INI */
  195.         WinQueryProfileString(hAB, "PMaux", "hWnd", "", hbuf, 40);
  196.   /* convert to a handle */
  197.         hWnd = (HWND)atol(hbuf);
  198.   /* create a shared buffer which can be read by another process */
  199.         if (DosAllocSeg(len, &sel, SEG_GETTABLE) == 0) {
  200.       /* make a long pointer to the buffer */
  201.         pchBuf = MAKEP(sel,0);
  202.       /* load it up */
  203.            for (i = 0; i < len; i++)
  204.             *(pchBuf+i) = *(str+i);
  205.       /* send it over */
  206.             if (WinIsWindow(hAB, hWnd))
  207.             WinSendMsg(hWnd, WM_USER, (MPARAM)len, (MPARAM)sel);
  208.       /* free the buffer */
  209.         DosFreeSeg(sel);
  210.         }
  211.         else  /* error, ring the bell */
  212.         WinAlarm(HWND_DESKTOP, WA_WARNING);    
  213. #endif
  214.  
  215.      To illustrate its usage, we have included a Presentation
  216. Manager template Spmtpl especially modified to transmit all
  217. messages received in the message loop to PMaux.  The technique is
  218. similar to that used in the corresponding Windows program.
  219.  
  220.      Most of the other features of Winaux are applicable to PMaux
  221. except that currently there is no logging capability and the
  222. initial placement and size of the window cannot be modified.  The
  223. latter feature was not implemented since in PM, one can run
  224. PMaux, size and place it once, and leave it for the duration of
  225. the OS2 session. 
  226.  
  227.  
  228.                  Remarks
  229.  
  230.      If you are trying to use Winaux or PMaux with a dynamic link
  231. library, you can still use the techniques described above for
  232. passing the message.  However, methods other than sprintf must be
  233. used to format the string since none of the printf family can be
  234. used when the stack segment does not coincide with the data
  235. segment of your program.
  236.  
  237.      Finally, note that both Spmtpl and Smltpl are very useful
  238. templates which can help you in starting your own Windows or PM
  239. program.
  240.